A CALib document (CADocumentRef) represents an OpenDoc™ Container 'odcn'. A CADocument may refer to a proxy part document, an OpenDoc part document, the clipboard document or the drag&drop document.
A CADocument can be the target of clone operations (CADataX.cpp), stream I/O operations (CAStream.cpp), and display operations.
A CADocument can be saved as either a flattened container stream or as an OpenDoc container file.
For container streams, the stream can be saved to a file or to a memory buffer.
For each open CADocument, CALib maintains an ODContainer object. For CALib savvy CA’s,
the ODContainer maintained by CALib is instantiated directly from the CA’s document file (as opposed to CALib maintaining a separate temporary file for the container.
CADocument Types
Proxy Document - Proxy documents are created and managed by the CA to allow embedding in application documents. Proxy documents may also may be used as temporary documents for data transfer.
OpenDoc Part Documents - used for documents dragged in from theFinder and for the Insert… menu. Obtained from CAOpenDocument(), opened read-only, in place (no temporary container is maintained).
Clipboard Document - obtained from CAGetClipboardDocument()
Drag&Drop Document - obtained from CAGetDragDropDocument()
CADocument API
pascal void CACreateDocument(
FSSpecPtr docSpec,
Handle docHandle );
docSpec - If docSpec is non-NULL, a file container is created.
docHandle - If docHandle is non-NULL, a memory container is created.
If docSpec & docHandle are both NULL, CALib creates a temporary file which contains the working container (The container is then streamed to a CA document file or saved in place, using CASaveDocument).
pascal void CASaveDocument(
CADocumentRef document,
CAOffset offset,
CASize* length,
FSSpecPtr docFile,
Handle* docHandle );
document - is the CADocument to be saved.
docFile - is the file for which an OpenDoc container document is created or the file where the container stream is written. If docFile is NULL (and docHandle is NULL) then the working container referred to by document is saved in place.
docHandle - is the buffer where the container stream is written (if docFile == NULL). If docHandle is NULL then the working container referred to by document is saved in place.
offset - is the offset into docFile or docHandle where the container stream is written.
length - length = 0 means to save document as an OpenDoc container file. If length != 0, it is an out parameter which receives the total length of the container stream.
Usage Matrix
Doc Type Target Offset Length Action
Proxy docFile 0 NULL Rename temp ctr file, save in place
Proxy docFile 0 non-NULL Rename temp ctr file, save in place
Proxy docHandle 0 NULL N/A
Proxy docHandle 0 non-NULL save temp mem container to docHandle
Proxy docFile non-0 non-NULL stream temp ctr file to docFile at offset
Proxy docHandle non-0 non-NULL stream temp ctr file to docHandle at offset
Proxy docFile = tempFile 0 NULL save in temp file container in place
Proxy docFile = tempFile non-0 NULL Illegal input
Proxy both NULL 0 NULL save temp file container in place
Proxy both NULL non-0 non-NULL Illegal input
Proxy both non-NULL n/a n/a Illegal input
pascal CADocumentRef CAOpenDocument(
CAOffset offset,
CASize* length,
FSSpecPtr docFile,
Handle docHandle );
docFile - If docFile is non-NULL it specifies the location of OpenDoc container. The container
is either embedded within the file (if offset != 0), or docFile specifies an
OpenDoc container file (CALib savvy).
docHandle - If docHandle is non-NULL it specifies the location of an OpenDoc container. The
container is either embedded within the memory refered to by docHandle (if offset != 0),
or docHandle specifies an OpenDoc memory container (CALib savvy).
offset - is the offset into newFile or docHandle where the container stream is written.
length - length ==0 indicates the target file is an OpenDoc container file.
Target Offset Action
docFile 0 docFile is an OpenDoc ctr file, opened in place
may be a CA doc file or a OpenDoc part document file.
docHandle 0 docHandle is a memory ctr, opened in place
docFile non-0 docFile contains a stream out ctr, temp file created.
docHandle non-0 docHandle contains a stream out ctr, temp file created.
both NULL n/a Illegal
docFile & docHandle n/a Illegal input
Clone API
The clone API is used by CA's for all types of data transfer. The clone API is the only means by which a CA can introduce or remove embedded frames to/from documents.
sourceFrameRef - specifies the frame being cloned. NULL if cloning the root part of a CADocument.
sourceDocument - specifies the CADocument in which sourceFrameRef is contained, or sourceFrameRef == NULL
destDocument - specifies the CADocument where the framed will be cloned to.
isRootFrameRef - TRUE if cloning a single embedded frames
cloneKey - cloneKey returned from CABeginClone()
Stream API
The stream API can be used by CA's to access the content value stream(s) associated with each CADocument.
See CALib API specification for descriptions of the following.
CARead()
CAWrite()
CAGetSize( )
CAGetOffset()
CASetOffset()
CAInsert()
CADelete()
Kind API
Single Kind
For CA's which need only support a single content value stream, the CASetDocumentKind() and CAGetDocumentKind()
routines can be used.
Multiple Kind
For CA's which require multiple content value streams, the following methods can be used. Multiple value streams are required for data transfer supporting multiple flavor types.
See CALib API specification for descriptions of the following.
